{smcl}
{hline}
help for {cmd:rsource}{right:(Roger Newson)}
{hline}

{title:Run R from inside Stata using an R source file and/or inline R code}

{p 8 21 2}
{cmd:rsource}
[ {helpb using} {it:R_source_filename} ] [ {cmd:,}
{cmdab:te:rminator}{cmd:(}{it:string}{cmd:)}
{cmdab:max:lines}{cmf:(}{it:#}{cmd:)}
{cmd:no}{cmdab:lo:utput} {cmdab:ls:ource}
{cmdab:rp:ath}{cmd:(}{it:R_pathname}{cmd:)}
{cmdab:ro:ptions}{cmd:(}{it:R_options}{cmd:)}
]

{pstd}
where {it:R_source_filename} is the name of a file containing R source code,
{it:R_pathname} is the name of the path of the R command to be used under the user's system,
and {it:R_options} is a set of options for the R command.


{title:Description}

{pstd}
{cmd:rsource} runs an R source program,
from an inline sequence of lines and/or from a file,
in batch mode from within Stata,
optionally listing the R output and/or the R source code
to the Stata Results window and/or the Stata {help log:log file}.
This allows the user to call R at a point in the execution of a Stata program
to input data files previously created by Stata
and/or to create output data files for later input by Stata.
The R software system must be installed on the user's system if the {cmd:rsource} package is to work.


{title:Options for use with {cmd:rsource}}

{p 4 8 2}
{cmd:terminator(}{it:string}{cmd:)} specifies a string,
to be used as a terminator for an inline R program inside the Stata program.
If {cmd:terminator()} is specified,
then {cmd:rsource} reads lines of R code from the following lines of the Stata program,
until it encounters a line containing only the {cmd:terminator()} string,
or until the number of lines of R code reaches the limit set by the {cmd:maxlines()} option (see below).
The user may specify a {cmd:terminator()} option and/or a {cmd:using} file qualifier,
both of which will be assumed to contain lines of R code for the R program to be run.
If the user specifies both a {cmd:terminator()} string and a {cmd:using} file qualifier,
then the inline R code will be placed before the R code from the file.

{p 4 8 2}
{cmd:maxlines(}{it:#}{cmd:)} specifies the maximum number of lines allowed
in the inline R code terminated by the {cmd:terminator()} string.
In default, {cmd:maxlines(1024}) is assumed.

{p 4 8 2}
{cmd:noloutput} specifies that the output from the R source code is not listed
to the Stata Results window and/or the Stata {help log:log file}.
If {cmd:noloutput} is not specified,
then the output from the R source code is listed.

{p 4 8 2}
{cmd:lsource} specifies that the R source code is listed
to the Stata Results window and/or the Stata {help log:log file}.
If {cmd:lsource()} is specified and {cmd:noloutput} is not specified,
then the R source file is listed before the output from the R command.

{p 4 8 2}
{cmd:rpath(}{it:R_pathname}{cmd:)} specifies a path name for invoking the R command.
If {cmd:rpath()} is not specified,
then it is set to the value of the {help macro:global macro} {hi:Rterm_path},
if that macro has been specified,
and to {hi:"Rterm.exe"} otherwise.
(See {hi:{help rsource##rsource_technote:Technical note}} below.)

{p 4 8 2}
{cmd:roptions(}{it:R_options}{cmd:)} specifies a set of options for the R command.
If {cmd:roptions()} is not specified,
then it is set to the value of the {help macro:global macro} {hi:Rterm_options},
if that macro has been specified,
and to the empty string {hi:""} otherwise.
(See {hi:{help rsource##rsource_technote:Technical note}} below.)


{title:Remarks}

{pstd}
The R statistical software system can be downloaded from {browse "http://www.r-project.org/":the R Project Website}.
It is complementary to Stata in its capabilities, as it contains implementations of many methods unavailable in Stata,
but does not have as many easy-to-use data management tools as Stata.
It may therefore be useful to be able to call R in batch mode from within a Stata do-file.

{pstd}
R can read Stata dataset files using the {cmd:read.dta} and {cmd:write.dta} modules of the {cmd:foreign} package.
Alternatively, it is possible to translate between Stata and R datasets using {browse "http://www.stattransfer.com/":Stat/Transfer},
which can be accessed from within Stata using the {helpb stcmd} package, downloadable from {help ssc:SSC}.
More recent R packages for exchange of data between Stata and R include {cmd:haven} and {cmd:readstata13}.
For more about import and export of data to and from R, refer to {it:R Data Import/Export}
(see {hi:{help rsource##rsource_references:References}})
Note that packages for import of data to R from Stata may be added at any time.
Note, also, that new {help version:Stata versions} may also be released,
which may or may not disable these R packages.

{pstd}
For more about the use of R for Stata users,
see {hi:{help rsource##rsource_references:Muenchen and Hilbe (2010)}}.


{marker rsource_technote}{...}
{title:Technical note}

{pstd}
{cmd:rsource} works by running the {cmd:Rterm.exe} program of R.
The assumed R program path is displayed by {cmd:rsource} before any other output,
and is the assumed name and address of the R program run by {cmd:rsource}.
If the user does not specify the {cmd:rpath()} and {cmd:roptions()} options,
then {cmd:rsource} sets defaults.
In the case of {cmd:rpath()}, the default is the value of the {help macro:global macro} {hi:Rterm_path},
if that macro has been specified,
and otherwise is {hi:"Rterm.exe"} if the operating system is Windows and {hi:"/usr/bin/r"} otherwise.
In the case of {cmd:roptions()}, the default is the value of the {help macro:global macro} {hi:Rterm_options},
if that macro has been specified,
and is the empty string {hi:""} otherwise.
Therefore, the user should either set the system default file search path to include the directory containing the current version of R,
or set the {help macro:global macros} {hi:Rterm_path} and {hi:Rterm_options} to sensible default values before using {cmd:rsource}.

{pstd}
The setting of default values for {hi:Rterm_path} and {hi:Rterm_options}
is probably done most easily by inserting two lines into the user's Stata {help profile:profile do-file}
to initialize these {help macro:global macros} every time the user starts Stata.
For instance, under Windows, if the user's {help profile:profile do-file} contains the lines

{p 8 12 2}{cmd:. global Rterm_path `"c:\r\R-2.5.0\bin\Rterm.exe"'}{p_end}
{p 8 12 2}{cmd:. global Rterm_options `"--vanilla"'}{p_end}

{pstd}
and the {cmd:Rterm.exe} program of R, in the user's system, has path {hi:c:\r\R-2.5.0\bin\Rterm.exe},
then the user does not need to specify the {cmd:rpath()} and {cmd:roptions()} options of {cmd:rsource},
because the R path is then set to its correct value,
and the R options are set to the sensible default value {hi:--vanilla}.
Other possible R options, which can be set using {cmd:roptions()},
are listed in Appendix B of {it:An Introduction to R}
(see {hi:{help rsource##rsource_references:References}}).

{pstd}
Note that, when the user downloads a new version of R, the installation process creates a new directory,
containing the new version of {hi:Rterm.exe}.
Therefore, when R is upgraded,
the user should either change the system default file search path,
or change the line of code in the {help profile:profile do-file} setting the {help macro:global macro} {hi:Rterm_path}.


{title:Examples}

{p 8 12 2}{cmd:. rsource using nitz2.R}{p_end}

{p 8 12 2}{cmd:. rsource using nitz2.R, lsource}{p_end}

{p 8 12 2}{cmd:. rsource using nitz2.R, noloutput roptions(--slave)}{p_end}

{pstd}
The following example illustrates the use of the {cmd:terminator()} option
to run an R program embedded inside a Stata program.
We use Stata to write the {cmd:auto} dataset to a file {cmd:myauto.dta}.
We then use {cmd:rsource} to run an instream R program,
which uses the module {cmd:read.dta} of the R package {cmd:foreign}
to read {cmd:myauto.dta} into a data frame in R,
and then lists this data frame and its attributes.
The module {cmd:read.dta} inputs a Stata dataset from a file
and outputs it to an R data frame,
with attributes that can be listed using the {cmd:attributes()} command in R.
The use of {helpb saveold} to write the dataset {cmd:myauto.dta}
is probably a sensible precaution,
because the user's version of the R package {cmd:foreign}
may not be able to read Stata datafiles produced by the latest version of Stata.
Note that, in {help version:Stata Version 14},
the {helpb saveold} command in this example should have the added option {cmd:version(12)}.

{p 8 12 2}{cmd:. sysuse auto, clear}{p_end}
{p 8 12 2}{cmd:. describe, full}{p_end}
{p 8 12 2}{cmd:. saveold myauto.dta, replace}{p_end}
{p 8 12 2}{cmd:. rsource, terminator(END_OF_R)}{p_end}
{p 8 12 2}{cmd:. library(foreign);}{p_end}
{p 8 12 2}{cmd:. rauto<-read.dta("myauto.dta", convert.f=TRUE);}{p_end}
{p 8 12 2}{cmd:. rauto;}{p_end}
{p 8 12 2}{cmd:. attributes(rauto);}{p_end}
{p 8 12 2}{cmd:. q();}{p_end}
{p 8 12 2}{cmd:. END_OF_R}{p_end}

{pstd}
The following example does the same things as the previous example,
using the {helpb outputst} module of the {help ssc:SSC} package {helpb stcmd}
to call {browse "http://www.stattransfer.com/":Stat/Transfer}
to output the {cmd:auto} dataset to an R workspace file {cmd:myauto.dta},
which is then input to R using {cmd:rsource}.
The present author has been advised that {browse "http://www.stattransfer.com/":Stat/Transfer}
is now the officially approved tool
for converting Stata datasets to R workspace files,
because, at the time of writing,
the module {cmd:read.dta} of the R library {cmd:foreign}
only reads Stata datasets in the formats of {help version:Stata versions 5-12},
and there is no promise from StataCorp that the {helpb saveold} command in Stata
will continue to output datasets in {help version:Stata versions 5-12} formats
in Stata versions 15 or higher.
Note that, in {help version:Stata Version 14},
the {helpb saveold} command in this example should have the added option {cmd:version(12)}.

{p 8 12 2}{cmd:. sysuse auto, clear}{p_end}
{p 8 12 2}{cmd:. describe, full}{p_end}
{p 8 12 2}{cmd:. saveold myauto.dta, replace}{p_end}
{p 8 12 2}{cmd:. rsource, terminator(END_OF_R)}{p_end}
{p 8 12 2}{cmd:. library(foreign);}{p_end}
{p 8 12 2}{cmd:. rauto<-read.dta("myauto.dta", convert.f=TRUE);}{p_end}
{p 8 12 2}{cmd:. rauto;}{p_end}
{p 8 12 2}{cmd:. attributes(rauto);}{p_end}
{p 8 12 2}{cmd:. q();}{p_end}
{p 8 12 2}{cmd:. END_OF_R}{p_end}

{pstd}
The following advanced example demonstrates the use of the {cmd:roptions()} option of {cmd:rsource}
with the {cmd:--args} option of the R command
to pass {help tempfile:Stata temporary filenames} to R.
This practice enables the user to pass temporary R workspace files between Stata and R,
knowing that these temporary files will be deleted after the current Stata session,
or even after the end of execution of the current {help do:do-file},
if {cmd:rsource} is executed in a {help do:do-file}.
This practice can also be generalized
to pass other {help macro:Stata macro values} to R,
apart from temporary filenames.
On the other hand, this practice seems, at present,
to require the user to have a high level of R programming knowledge.
This example is intended as a demonstration,
and only transfers the {cmd:auto} dataset to R,
and then transfers it back to Stata,
reporting the various changes that have been made by {browse "http://www.stattransfer.com/":Stat/Transfer}
in the course of transferring the dataset in both directions.
The present author is currently thinking about how to make the integration of R and Stata easier to use,
and will welcome any suggestions from other users.

{p 8 12 2}{cmd:. sysuse auto, clear}{p_end}
{p 8 12 2}{cmd:. describe, full}{p_end}
{p 8 12 2}{cmd:. tempfile tf1 tf2}{p_end}
{p 8 12 2}{cmd:. outputst r "`tf1'" /y}{p_end}
{p 8 12 2}{cmd:. rsource, terminator(END_OF_R) roptions(`" --vanilla --args "`tf1'" "`tf2'" "')}{p_end}
{p 8 12 2}{cmd:. trailargs<-commandArgs(trailingOnly=TRUE);}{p_end}
{p 8 12 2}{cmd:. trailargs;}{p_end}
{p 8 12 2}{cmd:. loaded<-load(trailargs[1]);}{p_end}
{p 8 12 2}{cmd:. loaded;}{p_end}
{p 8 12 2}{cmd:. loaded[1];}{p_end}
{p 8 12 2}{cmd:. .GlobalEnv[[loaded[1]]];}{p_end}
{p 8 12 2}{cmd:. myauto<-.GlobalEnv[[loaded[2]]];}{p_end}
{p 8 12 2}{cmd:. .GlobalEnv[[loaded[2]]]<-NULL;}{p_end}
{p 8 12 2}{cmd:. ls();}{p_end}
{p 8 12 2}{cmd:. myauto;}{p_end}
{p 8 12 2}{cmd:. attributes(myauto);}{p_end}
{p 8 12 2}{cmd:. save(myauto, file=trailargs[2]);}{p_end}
{p 8 12 2}{cmd:. END_OF_R}{p_end}
{p 8 12 2}{cmd:. clear}{p_end}
{p 8 12 2}{cmd:. inputst r "`tf2'"}{p_end}
{p 8 12 2}{cmd:. describe, full}{p_end}
{p 8 12 2}{cmd:. char list}{p_end}


{title:Author}

{pstd}
Roger Newson, Imperial College London, UK.{break}
Email: {browse "mailto:r.newson@imperial.ac.uk":r.newson@imperial.ac.uk}


{marker rsource_references}{...}
{title:References}

{phang}
Muenchen R. A. and J. M. Hilbe.
{it:R for Stata users}.
New York, NY: Springer; 2010.

{phang}
Venables W. N., D. M. Smith, and the R Development Core Team.
{it:An Introduction to R}.
Downloadable from
{browse "http://www.r-project.org/":the R Project Website}.

{phang}
The R Development Core Team.
{it:R Data Import/Export}.
Downloadable from
{browse "http://www.r-project.org/":the R Project Website}.


{title:Also see}

{p 4 13 2}
{bind: }Manual: {hi:[GSW] C.3 Executing commands every time Stata is started},
{hi:[GSM] C.1 Executing commands every time Stata is started},
{hi:[GSU] C.1 Executing commands every time Stata is started}
{p_end}
{p 4 13 2}
On-line: help for {help profile}, {help profilew}, {help profilem}, {help profileu}{break}
         help for {helpb stcmd} if installed
{p_end}
